home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / DISK / DFS10.ARJ / DFS.DOC next >
Text File  |  1992-03-02  |  22KB  |  482 lines
  1.        
  2.        +---------------------------------------------------------------------+
  3.        | Documentation for DiskFileSearcher  v1.0                   02-25-92 |
  4.        +---------------------------------------------------------------------+
  5.  
  6.        DiskFileSearcher v1.0 Copyright 1992 HCS Software. All Rights Reserved.
  7.  
  8.        Documentation for DiskFileSearcher v1.0 Copyright 1992 HCS Software.
  9.                                                All Rights Reserved.
  10.  
  11.        +---------------------------------------------------------------------+
  12.  
  13.        Please refer to the end of this documentation for licensing,
  14.        registration, how to contact HCS Software, and limits of liability
  15.        and disclaimer of warranty information.
  16.  
  17.  
  18.        CONTENTS:
  19.        
  20.        o DFS OVERVIEW
  21.        o WHAT'S NEW WITH v1.0?
  22.        o BRIEF DESCRIPTION OF DFS AND ITS PARAMETERS
  23.        o HOW TO USE DFS
  24.        o SETTING THE DFS ENVIRONMENTAL VARIABLE
  25.        o DFS USAGE EXAMPLES
  26.        o DESIGN ISSUES AND PERFORMANCE COMPARISONS
  27.        o TECHNICAL DATA
  28.        o LICENSING INFORMATION
  29.        o REGISTRATION INFORMATION
  30.        o HOW TO CONTACT HCS SOFTWARE
  31.        o LIMITS OF LIABILITY AND DISCLAIMER OF WARRANTY
  32.        o SPECIAL THANKS
  33.        o DFS VERSION AND UPDATE HISTORY
  34.        
  35.        +---------------------------------------------------------------------+
  36.        
  37.        o DFS OVERVIEW
  38.  
  39.          DiskFileSearcher is an extremely fast and powerful file finding
  40.          utility.  DFS was developed to meet a variety of needs not currently
  41.          addressed, or satisfactorily addressed, by other available file
  42.          search utilities.  Most of these file search utilities lack several
  43.          useful search options, file information options, display format
  44.          options, sequential directory scanning, and the ability to execute
  45.          an external command at each matching file.  DFS meets an extensive
  46.          number of user needs, including some features not readily available
  47.          with other similar utilities.  DFS can also be extended by use of
  48.          external programs to act as a archive listing utility, a file
  49.          deletion utility, or even a quick text file displayer (see DFS USAGE
  50.          EXAMPLES section below for details).  Futhermore, DFS can be set to
  51.          go to the first match found directory making it easier than
  52.          navigating through deep subdirectory listings.
  53.  
  54.  
  55.        o WHAT'S NEW WITH v1.0?
  56.  
  57.          First of all, DFS v1.0 has undergone a significant code rewrite
  58.          allowing many new features in approximately the same size EXE file.
  59.          DFS is now 11% faster than v0.1 and provides greatly enhanced search
  60.          capabilities.  DFS v1.0 now recognizes and supports DOS redirection
  61.          (the > and >> commands) allowing simultaneous file listings on the
  62.          video screen and to a file or to a printer.  DFS v1.0 has greatly
  63.          enhanced wildcard filespec processing; intelligent processing would
  64.          be an accurate description (see DFS USAGE EXAMPLES section below).
  65.          The commands used to execute external or DOS commands have been
  66.          changed to allow easier usage.  DFS also recognizes the DFS
  67.          environmental variable so that DFS can be customized to execute
  68.          with user preferred options already selected.  Finally, there have
  69.          been a several other display changes and internal changes and one
  70.          minor bug fix.  Please refer to DFS VERSION AND UPDATE HISTORY
  71.          section below for a complete update history.
  72.  
  73.  
  74.        o BRIEF DESCRIPTION OF DFS AND ITS PARAMETERS:
  75.  
  76.          DFS execution:  DFS [options] [d:][path]filespec [options]
  77.  
  78.          [d:]      is the optional drive specification (A:, b:, c:, E: etc.)
  79.          [path]    is the optional search path (\, \dos\, \TOOLS\SUB1\, etc.)
  80.          filespec  is the required file specification (*.*, .doc, work*.doc,
  81.                    pcpart?0., ., ..\test*.*, \*., etc.)
  82.  
  83.          options   are the optional command parameters that allow different
  84.                    search guidelines, search restrictions, display
  85.                    redirection, and so forth.
  86.  
  87.          The options are:
  88.  
  89.            /A<h,s,r,a>              search for files with specific Attributes
  90.                                       set
  91.            /B                       output displayed with Bios routines
  92.            /D<mm/dd/yy><-mm/dd/yy>  minimum-maximum file Date to find
  93.            /E                       display separately Each directory searched
  94.            /Fstring                 searches for string Fragment in file name
  95.            /G[number]               Goto directory of number matching file
  96.                                       found or first match if no number is
  97.                                       specified
  98.            /L[number]               Lists number amount of files before pausing
  99.                                       or pause after each if no number is
  100.                                       specified
  101.            /N                       No recursion into subdirectories
  102.            /P                       display using DOS Pathname only
  103.            /Rdrive1-drive2          search Range of disk drives drive1 to
  104.                                       drive2
  105.            /Sminsize-maxsize        search file Size range [min-max file size
  106.                                       for match]
  107.            [command [%]]            execute a command for each match;
  108.                                       [] or "" may be used as delimiters;
  109.                                       % represents found file substitution
  110.                                       position (optional, but almost always
  111.                                       used)
  112.  
  113.  
  114.          Note that DFS's screen output can be paused by hitting any key other
  115.          than ESC or CTRL-C, and continued with another keypress.  ESC or
  116.          CTRL-C will halt DFS and display the current statistics to that
  117.          point.  Also, options can be specified before and after the filespec
  118.          in upper or lower case.
  119.  
  120.  
  121.        o HOW TO USE DFS:
  122.        
  123.          DFS is extremely easy to use for both simple search needs and more
  124.          complex file search and maintenance demands.  For example, to list
  125.          all files on the current drive starting from the root directory type
  126.          the following command line at the dos prompt:
  127.        
  128.            DFS \  (or you could type DFS \*.*)
  129.        
  130.          This will display every file on the current drive, including hidden
  131.          and system files.  To display all files on drive B: you would enter:
  132.  
  133.            DFS b:\
  134.  
  135.          To search for specific file names, such as all .DOC files in the
  136.          \INSTRUCT directory and its subdirectories on drive A: you would
  137.          enter:
  138.  
  139.            DFS a:\instruct\*.doc
  140.        
  141.          Searching for parts of file names is accomplished by the using the
  142.          /F parameter.  For example:
  143.  
  144.            DFS c:\.exe /finst
  145.  
  146.          would display all files ending with .EXE and containing INST in
  147.          the file name on drive C:, note that *.EXE is assumed.
  148.  
  149.          DFS output defaults to direct video memory writes (with snow
  150.          checking).  You may redirect output to a printer (or another file
  151.          for that matter) in addition to the video screen as follows:
  152.  
  153.            DFS \ > prn
  154.  
  155.          This line would list all files on the current drive to the default
  156.          printer.  Please refer to your DOS manual about the redirection
  157.          ('>') command for further information.
  158.  
  159.          The [] and "" options are special options that cause DFS to execute
  160.          the designated command (and its specified parameter(s), if any) for
  161.          each matching file (represented by the % in the command).  The
  162.          matching file's pathname is substituted for the %.  Some examples:
  163.  
  164.            DFS \ "dothis % c:\temp /a /b"
  165.  
  166.          causes DFS to take each matching file and execute DOTHIS as if you
  167.          had entered the command from the DOS prompt:
  168.  
  169.            DOTHIS d:\path\filename.ext c:\temp /a /b
  170.  
  171.          DFS will search the DOS PATH for the command by default.  If the
  172.          command is not an internal DOS command or not somewhere on the DOS
  173.          PATH then the full path must be specified (the same way as you
  174.          would have to from the DOS prompt).  Note that if the command is
  175.          the last parameter called when DFS is executed then the trailing
  176.          ] or " is not necessary.  See DFS USAGE EXAMPLES for more examples.
  177.  
  178.  
  179.        o SETTING THE DFS ENVIRONMENTAL VARIABLE
  180.  
  181.          DFS v1.0 now supports an environmental variable to facilitate the
  182.          use of particular options or settings regularly desired by the user.
  183.  
  184.          Setting the variable is simple and can be done from the DOS prompt
  185.          or AUTOEXEC.BAT as follows:
  186.  
  187.            SET DFS=[option] [option] [option]...
  188.  
  189.          For example, to set DFS to always search from the root directory of
  190.          the default drive using BIOS output enter the following at the DOS
  191.          prompt or on its own line the AUTOEXEC.BAT file:
  192.  
  193.            set dfs=\ /b
  194.  
  195.          Now every time that DFS is entered at the DOS prompt it will use
  196.          those default settings, plus any additional settings entered at the
  197.          prompt.  Note that all options used in the DFS environmental
  198.          variable, except for the filespec, cannot be cleared at the command
  199.          line.  To override the filespec simply enter a new  filespec (e.g.
  200.          DFS *.*), however all other settings still apply.  In order to clear
  201.          the variable enter SET DFS= at the DOS prompt or eliminate the line
  202.          from the AUTOEXEC.BAT file.
  203.  
  204.  
  205.        o DFS USAGE EXAMPLES:
  206.        
  207.          The following are common DFS uses with brief descriptions.
  208.        
  209.          - DFS a:
  210.        
  211.            displays all files in the current DOS directory (not necessarily
  212.            the root directory) on drive A: and all of its subdirectories.
  213.  
  214.  
  215.          - DFS \dfs.exe /p
  216.        
  217.            displays all occurences of DFS.EXE on the current drive using the
  218.            DOS pathname format (i.e. d:\path\filename.ext).
  219.  
  220.  
  221.          - DFS /b temp\.doc
  222.  
  223.            displays all files with .DOC extensions in the subdirectory TEMP
  224.            off of the current directory on the current drive through the BIOS.
  225.  
  226.  
  227.          - DFS /n *.* /ahs  (alternate usage: DFS . /ahs)
  228.  
  229.            displays only those files in the current directory (no subdirectory
  230.            recursion) if they have their hidden and system attributes set,
  231.            regardless of the other attribute settings.  When the filespec is
  232.            the current directory '.' DFS assumes no recursion.
  233.  
  234.  
  235.          - DFS \ /d5-18-88- /l10 /fq /e
  236.  
  237.            displays all files with a 'Q' in their name and a date stamp of
  238.            May 18, 1988 or older on the current drive in groups of 10 before
  239.            pausing for user keypress to continue.  Each directory that is
  240.            searched is displayed regardless if a file match in that directory
  241.            is found.
  242.  
  243.  
  244.          - DFS /f$$$ \ /d10/2/80-5-31-90 /g5
  245.        
  246.            displays all files on the current drive with '$$$' in their names
  247.            and having a date stamp between October 2, 1980 and May 5, 1990
  248.            (yes, '-' and '/' can be used as month, day and year delimiters,
  249.            but the range separator must be a '-').  The file display is
  250.            halted after the 5th matching file is found and the user is placed
  251.            in that directory.
  252.  
  253.  
  254.          - DFS \*.* /ra-c /s100000-500000
  255.        
  256.            displays all files on drives A:, B: and C: with sizes between 100k
  257.            and 500k bytes.
  258.  
  259.  
  260.          The following examples demonstrate the full potential of DFS.
  261.          Exercise due caution when using DFS with the [] or "" parameters.
  262.  
  263.          - DFS c:\*.old [del %]
  264.  
  265.            displays all files on drive C: with OLD extension and uses DOS'
  266.            DEL (ERASE) command to delete each one.  Note that DOS' DEL cannot
  267.            delete read-only files.  This example is provided to forewarn the
  268.            user about careless use of the [] and "" parameters.
  269.  
  270.  
  271.          - DFS *.doc "type %
  272.  
  273.            displays all .DOC files in the current directory and its
  274.            subdirectories and uses the DOS command TYPE to display each file.
  275.  
  276.  
  277.          - DFS *.doc "type %" > docfile
  278.  
  279.            displays all .DOC files in the current directory and its
  280.            subdirectories and uses the DOS command TYPE to copy each one to
  281.            the file DOCFILE.
  282.  
  283.  
  284.          - DFS .zip "pkunzip -vb %"
  285.  
  286.            displays all .ZIP files in the current DOS directory and its
  287.            subdirectories and executes PKUNZIP to display each of the .ZIP
  288.            files' contents.  PKUNZIP is a registered trademark of PKWARE, Inc.
  289.  
  290.  
  291.          - DFS [copy % b:\holding /v] \*.txt /rc:-g:
  292.  
  293.            displays all .TXT files on drives C: through G: and copies each to
  294.            the \HOLDING directory of drive B: using DOS' copy command with
  295.            verify turned on.
  296.  
  297.  
  298.          - DFS e:\ /arsh [attrib -h -r -s
  299.  
  300.            displays all files on drive E: with hidden, read-only and system
  301.            attribute settings only and uses the external DOS command ATTRIB
  302.            to clear those attribute settings only.
  303.  
  304.          - DFS a:\doc\*.doc /fpc "xe %
  305.  
  306.            displays all .DOC files, with 'PC' in their names, on drive A:'s
  307.            \DOC directory, and executes XERASE (also by HCS Software) to
  308.            prompt before deleting each matching file.
  309.  
  310.  
  311.        o DESIGN ISSUES AND PERFORMANCE COMPARISONS
  312.  
  313.          DFS was developed to be an extremely fast and powerful file search
  314.          utility with an extensive number of useful options.  A significant
  315.          development factor was the ability to find and display all files
  316.          regardless of attribute settings.  Furthermore, the ability to
  317.          examine a particular directory branch without having to run through
  318.          the entire hard disk was an essential feature.
  319.  
  320.          One design requirement for DFS was found to be surprisingly ignored
  321.          by several other similar utilities--always displaying the child
  322.          subdirectories after their immediate parent directories.  DFS
  323.          examines the directory structure by searching each child directory
  324.          BEFORE proceeding back to the parent directory (or worse yet, other
  325.          directory branches and then haphazardly jumping back).  This results
  326.          in a cleaner, logically organized output especially when displaying
  327.          a hard disk with hundreds of related, nested subdirectories.
  328.  
  329.          DFS was designed to meet high performance needs of PC users.
  330.          The search time results (in seconds) to find all files in all
  331.          directories of the test hard disk of several similar utilities
  332.          are below.  These results were achieved on a 40MHz 80386 clone with
  333.          a 105Mb hard disk, no caching, optimized hard disk, FILES=30,
  334.          BUFFERS=20, 2123 files in 114 directories using 37,599,718 bytes.
  335.  
  336.           tested program |program||full file info|less than 64k|accurate  |
  337.           name           |version||displayed     |memory needed|statistics|
  338.           ---------------+-------++--------------+-------------+----------+
  339.           NORTON FL      |  6.0  || 66.5    100% |     YES     |    NO    |
  340.           FINDIT         |  1.0  || 64.1    104% |     YES     |    NO    |
  341.           PCTOOLS FF     |  7.1  || 44.4    150% |      NO     |   YES    |
  342.           WIZ            |  2.0  || 32.9    202% |     YES     |   YES    |
  343.           FIND           |  2.21 || 19.7    338% |      NO     |    NO    |
  344.                          |       ||              |             |          |
  345.           DFS            |  1.0  || 21.6    308% |     YES     |   YES    |
  346.  
  347.          Note that some of the above utilities (DFS excluded, naturally)
  348.          found either one too many files, were unable to locate hidden and
  349.          system files, or displayed only partially useful file information.
  350.          Finally, DFS can handle up to 32 levels of subdirectories, unlike
  351.          some file finding utilities that were tested, but not included for
  352.          that reason.
  353.  
  354.  
  355.        o TECHNICAL DATA
  356.  
  357.          DFS is 'well-behaved' only if the /B option is used, which sends
  358.          output through the BIOS.  DFS otherwise makes use of direct video
  359.          memory screen writes for greatly improved display output.
  360.  
  361.          DFS does not make any disk write accesses, unless an external
  362.          command is executed that would otherwise do so.
  363.  
  364.          DFS v1.0 was written exclusively in Turbo Pascal v6.0.
  365.  
  366.  
  367.        o LICENSING INFORMATION:
  368.        
  369.          DiskFileSearcher (DFS) is copyrighted software.
  370.  
  371.          The user is not obtaining title to this software or any copyright
  372.          rights.  DFS may not be modified, translated, decompiled, or
  373.          disassembled.
  374.  
  375.          DFS is free to use, copy, and distribute, as long as no usage,
  376.          copying, or distribution fee is charged, and DFS is accompanied by
  377.          its component files.  A maximum fee of $2 (US) may be charged for
  378.          the costs involved in copying and/or distributing copies of this
  379.          software by user groups, shareware distributors, bulletin board
  380.          services, and similar software outlets.
  381.  
  382.          Business, institutional, organizational, and government users must
  383.          register DFS after a 30 day evaluation period.  Use on more than one
  384.          computer by business, institutional, organizational, or government
  385.          users, or use on a network by business, institutional,
  386.          organizational, or government users requires a site-license.
  387.          For more information please contact HCS Software.
  388.  
  389.  
  390.        o REGISTRATION INFORMATION:
  391.        
  392.          If you find DFS useful, you are encouraged to register your copy
  393.          for $8 (US).  Please use the accompanying REGISTER.DFS file for
  394.          registration.  Registered users are automatically registered for
  395.          the next version of DFS at no additional charge.  Paid registration
  396.          does not necessarily constitute a paid site-license.
  397.  
  398.          This software was developed to meet demands not currently or fully
  399.          addressed by other similar software and your registration will
  400.          encourage further development and help promulgate the availability
  401.          of superior and competitively priced software.
  402.  
  403.  
  404.        o HOW TO CONTACT HCS SOFTWARE:
  405.        
  406.          Chris Haltiner                    
  407.          HCS Software
  408.          7411 Whispering Pines Drive       
  409.          Dallas, Texas 75248  USA
  410.        
  411.          HCS Software/Haltiner Computer Services  (214) 458-0789
  412.        
  413.          Chris Haltiner  CompuServe [CIS] 72607,2766
  414.        
  415.        
  416.        o LIMITS OF LIABILITY AND DISCLAIMER OF WARRANTY:
  417.        
  418.          HCS SOFTWARE SPECIFICALLY DISCLAIMS ALL WARRANTIES RELATING TO THIS
  419.          SOFTWARE, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, ANY
  420.          IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
  421.          PURPOSE.  HCS SOFTWARE SHALL NOT BE LIABLE FOR ANY DAMAGES, INCLUDING
  422.          BUT NOT LIMITED TO, LOSS OF PROFIT OR DATA, OR SPECIAL, INCIDENTAL,
  423.          CONSEQUENTIAL, DIRECT, OR INDIRECT DAMAGES IN CONNECTION WITH, OR
  424.          ARISING OUT OF THE PERFORMANCE, APPLICATION, USE OR INABILITY TO USE
  425.          THIS SOFTWARE, EVEN IF HCS SOFTWARE HAS BEEN ADVISED OF THE
  426.          POSSIBILITY OF SUCH DAMAGES OR CLAIMS.
  427.  
  428.          IN NO EVENT SHALL HCS SOFTWARE'S LIABILITY FOR ANY DAMAGES EVER
  429.          EXCEED THE PRICE PAID FOR THE LICENSE TO USE THIS SOFTWARE,
  430.          REGARDLESS OF THE FORM OF CLAIM.
  431.  
  432.          THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THIS SOFTWARE
  433.          IS ASSUMED BY THE USER.
  434.  
  435.  
  436.          GOVERNING LAW AND GENERAL PROVISIONS:
  437.  
  438.          This agreement is governed by the laws of the State of Texas and
  439.          shall inure to the benefit of HCS Software.  Any action or
  440.          proceeding brought by either party the other arising out of or
  441.          related to this agreement shall be brought only in a STATE or
  442.          FEDERAL COURT of competent jurisdiction located in Dallas County,
  443.          Texas. The parties hereby consent to in personam jurisdiction of
  444.          said courts.
  445.  
  446.  
  447.        o SPECIAL THANKS:
  448.  
  449.          I would like to thank the following individuals for their comments
  450.          and suggestions: David Brinner and Jeremy Pohl.
  451.  
  452.  
  453.        o DFS VERSION AND UPDATE HISTORY:
  454.  
  455.          0.1  - 01-21-92
  456.               - first release
  457.  
  458.          0.1a - 01-26-92
  459.               - /A, /a with Archive setting search corrected to work with all
  460.                 four variations (/AA, /aa, /Aa and /aA) instead of opposite
  461.                 cases only (aA and Aa)!?!
  462.  
  463.          1.0  - 02-02-92 to 02-25-92
  464.               - added more final statistics
  465.               - added special filespec wildcard processing
  466.               - /g# (goto match #) function without a number defaults to
  467.                 first match
  468.               - execute command call and delimiters changed to [] or ""
  469.               - DOS redirection recognized and fully supported
  470.               - recursive directory search routine rewritten
  471.               - error result description removed
  472.               - will find and search hidden directories
  473.               - default display mode changed to verbose file information
  474.               - file display match indicator bug fixed (this may, but probably
  475.                 didn't, cause skewed statistics in previous versions)
  476.               - recognizes DFS environmental variable
  477.               - allows display of each directory searched regardless of file
  478.                 match in that directory
  479.  
  480.        +---------------------------------------------------------------------+
  481.        end of DFS documentation
  482.